home *** CD-ROM | disk | FTP | other *** search
/ Internet Tools (InfoMagic) / Internet Tools.iso / mail / uucp / uubatch.105.Z / uubatch.105 / README < prev    next >
Text File  |  1993-06-07  |  11KB  |  281 lines
  1.  
  2. ***** README file, uubatch version 1.0.5 *****
  3.  
  4. uubatch : A UUCP rmail batcher/debatcher package.
  5.  
  6. Authors :    Gil Tene        (devil@hellnet.org)
  7.         Baruch Cochavy        (blue@dduster.hellnet.org)
  8.  
  9.  
  10. Problem definition and solution approach :
  11.  
  12. Problem definition : the uubatch package is aimed at increasing UUCP
  13. e-mail transfer efficiency. The main efficiency drawback in UUCP e-mail
  14. (via the rmail command) is the small UUCP job sizes. Most mail messages
  15. tend to be short (less than 5K). Each such message is queued separately
  16. by UUCP, and is transferred separately by uucico. This make for a very
  17. high job-count/Kbytes ratio. Each job transfer (two files per job)
  18. usually takes more than 8 seconds on most links regardless of job
  19. size. On modems with UUCP spoofing the drawback is even more noticeable,
  20. as they have a very high UUCP transfer efficiency WITHIN each
  21. file transferred, but suffer just like any other modem on per-file
  22. delays. This means that UUCP spoofing efficiency is not really
  23. utilized on short e-mail transfers.
  24.  
  25. The solution is simple: reduce the job-count/Kbyte count, thereby
  26. increasing efficiency. This is done by "batching" several e-mail
  27. messages together into one UUCP job, thus suffering only one
  28. per-job delay for each batch.
  29.  
  30. This solution has been implemented in other packages (Smail 3.1
  31. compressed batched SMTP mail for one) by having the mailer NOT
  32. deliver rmail jobs to UUCP immediately, but rather queue them 
  33. separately and batch them together into one large job every once
  34. in a while. This technique has two major drawbacks: It forces
  35. the ***mailers*** on both sides to support the protocol, and
  36. it causes delays in mail delivery (you balance efficiency against
  37. delivery speed).
  38.  
  39. The uubatch package provides the solution by batching e-mail 
  40. transfers AFTER they have been queued by UUCP as rmail commands,
  41. and "debatching" them back on the other side as normal UUCP rmail 
  42. commands. 
  43.  
  44. The uubatch package offers several advantages over other e-mail
  45. batching schemes :
  46.  
  47. 1)  It is independent of the mailer used. It will work on spooled
  48.     rmail commands, which are the same for all mailers.
  49.  
  50. 2)  It doesn't cause any delay in mail delivery. It batches already
  51.     queued jobs. If it doesn't get a chance to batch a mail message
  52.     before a poll occurs, that message will be transferred as normal
  53.     unbatched rmail.
  54.  
  55. 3)  It does re-batching. This makes sure that batched jobs are used
  56.     to their maximum efficiency. You can run the batching script as
  57.     often as you like without worrying about loosing transfer 
  58.     efficiency (it won't make lots of small batches).
  59.  
  60. 4)  The code is SIMPLE, relatively short, easy to understand and to 
  61.     port. It will not interfere or clash with mailer configurations.
  62.  
  63.  
  64. Implementation mechanism :
  65.  
  66. The mechanism is in two parts :
  67.  
  68. Sending end: the batcher : uubatch, uucplock (C programs)
  69.  
  70.   The uubatch program is run periodically on [specified] outgoing spool 
  71.   directories. In each spool directory uubatch batches together any rmail 
  72.   jobs and any previous batches (uudebat or uucdebat jobs) it finds that 
  73.   are small enough (execution settable critical size).
  74.  
  75.   The batching is very simple : Once a batchable job is identified, it's 
  76.   data file names (both local and final remote names) are parsed. The data 
  77.   files are then appended to a "uubatch" file with a simple envelope that 
  78.   includes their final remote names and enables simple extraction on the 
  79.   other side. In the case of re-batching of batch jobs (uudebat and uucdebat) 
  80.   the contents of the job's data file (uncompressed in the case of uucdebat) 
  81.   is simply appended to the "uubatch" file. Once all rmail/uudebat/uucdebat 
  82.   jobs are batched, or once the "uubatch" data file reaches a given critical 
  83.   size, the following command is executed :
  84.  
  85.   uux - -r nodename!uudebat < batchname
  86.  
  87.   (or compress -c | batchname uux - -r nodenanme!uucdebat)
  88.  
  89.   Re-batching of batched jobs is ONLY done if there is at least one rmail
  90.   job in the queue, and only on jobs that are small enough to be re-batched.
  91.   This avoids avoids any unneeded re-batching.
  92.  
  93.   The entire batching process is done while locking the UUCP node
  94.   via a uucp lock mechanism (I hacked this up from the BSD tip uucplock.c
  95.   code, you can hack it if your locking mechanism is non-HDB or non-BSD). 
  96.   This makes sure that no double or partial jobs are transmitted. 
  97.   The batching process will only batch files which have been modified more 
  98.   than a specified time ago, to avoid any possible synchronization clashes 
  99.   with any rmail jobs being created at the same time.
  100.   
  101. Receiving end: the debatcher : uudebat (C program) and uucdebat (script)
  102.  
  103.   The uucdebat script is trivial : "uncompress | uudebat".
  104.  
  105.   uudebat: This VERY simple C program accepts as input a "uubatch" file.
  106.   The file contains destination file names and their file contents
  107.   (each line of the contents is superseded by a # char.). The 
  108.   extraction is trivial. It is done into the executing node's 
  109.   spool directory (the executing node is figured out from UU_MACHINE).
  110.   This is ALL that needs to be done, since the files will then be 
  111.   picked up by uuxqt just as if they were put there by uucico directly.
  112.   The file names and contents are EXACTLY what they were supposed to be,
  113.   and they will all look like normal rmail jobs to uuxqt.
  114.  
  115.   The debatcher program is the one security people would need to look at 
  116.   for possible holes, and that is why it is a C program (efficiency is 
  117.   another reason). It will ONLY extract files into the connected node's 
  118.   incoming spool directory, and it can't be fooled (I believe) into doing
  119.   anything bad by hacking a bogus "uubatch" file and feeding it into 
  120.   uudebat.
  121.  
  122.  
  123. Files:
  124.  
  125.   README     --    This file.
  126.  
  127.   Makefile    --    A trivial Makefile, it makes the uubatch, uucplock,
  128.             and uudebat executables. Has several defines to 
  129.             look at.
  130.  
  131.   uubatch.c     --    The job batcher, see mechanism explanation above.
  132.  
  133.   uucplock.c     --    A locking mechanism. Based on the BSD tip uucplock.c
  134.             code (and heavily modified for HDB UUCP). See the 
  135.             BSD Copyright notice in this file.
  136.  
  137.   uudebat.c    --    The job debatcher program, see mechanism explanation
  138.             above.
  139.  
  140.   uucdebat    --    A simple shell script for compressed debatching,
  141.             see mechanism explanation above.
  142.  
  143.   uubatch.1    --    man page. (read with : nroff -man uubatch.1 | more)
  144.  
  145.   uudebat.1    --    man page. (read with : nroff -man uudebat.1 | more)
  146.  
  147.  
  148.  
  149. Installation:
  150.  
  151. - Unpack the package, decide on where you want to install the uudebat
  152.   and uucdebat commands (they need to be executable by remote via UUCP,
  153.   just like rmail). Check and modify the following parameters in the 
  154.   following files :
  155.  
  156.   Makefile :     Make sure it will make the files ok. (compiler, 
  157.         flags, etc.) Read the description of the defined
  158.         variables and edit their values if needed.
  159.  
  160.   uucdebat :    Make sure that the pathnames for uncompress and uudebat
  161.         are correct. It is recommended that you use full path
  162.         names to avoid errors. A mistake here is the only place
  163.         we know of that causes messages to be silently 
  164.         bit-bucketed.
  165.  
  166.   uucplock.c :    If you have a non-BSD and non-HDB UUCP system, try to
  167.         find out what UUCP locking mechanism is used in your
  168.         system and change this file if needed. 
  169.         Make sure PMAX is set to the maximum filename length 
  170.         on your system. If the program does not compile as-is
  171.         and you do not find a predefined symbol for this value,
  172.         define PMAX to be 255.
  173.  
  174.   uubatch.c :    I don't expect any need to change this file.
  175.  
  176.   uudebat.c :    Take a look at the definition of PMAX. It should be
  177.         equal to the maximum length of a path name on your
  178.         system. If the program does not compile as-is, and
  179.         you do not find a predefined symbol for this value,
  180.         define PMAX to be 255.
  181.  
  182.   Make the uubatch, uucplock, and uudebat programs with make(1).
  183.  
  184. - Install the uudebat and uucdebat commands in a proper location, 
  185.   so that they will be able to execute as a remote UUCP command
  186.   (/usr/bin or /bin is the usual place). It is advisable to set the
  187.   owner uid and group of the files to be uucp.
  188.  
  189. - Make sure that the UUCP permissions file allows remote nodes
  190.   (with which you wish to do uubatch batching) to execute the
  191.   uudebat and uucdebat commands.
  192.  
  193. - Read the uubatch.1 man page for description of usage and meaning of 
  194.   flags in uubatch.
  195.  
  196. - Run some manual test batches to an adjacent node, manually invoking 
  197.   uubatch using syntax like:
  198.  
  199.         uubatch foobar            
  200.     or: uubatch -c foobar  
  201.  
  202.   (These runs will require supervisor or uucp access rights).
  203.  
  204.     NOTE :
  205.  
  206.     When running tests, and after instalation too, the uubatch and
  207.     uucplock binaries should be located in the same directory. uubatch
  208.     invokes uucplock, and expects it to be runnable with the same
  209.     path prefix it (uubatch) was run with. )
  210.  
  211.   and read the resulting data file created in UUCP spool directory.
  212.   The file should be readable using 'cat {filename}' or 'zcat < {filename}'
  213.   for compressed batches. Once you are satisfied that the batching 
  214.   is done right, allow it to go through to the remote node, and verify
  215.   that it has been correctly debatched (It would help if the remote site
  216.   would allow uudebat and uucdebat execution. :-) 
  217.  
  218.  
  219. - Edit uucp's crontab entry, and add an execution of :
  220.  
  221.         /usr/local/uucp/uubatch node [node,...]
  222.  
  223.   (with optional -c for compression, read description of other
  224.    flags in uubatch.1 man page for details on how to control batch 
  225.    file sizes)
  226.  
  227.   Set intervals for execution in any way you like. Remember that 
  228.   there is no need to open "large" time windows for batching, since
  229.   small jobs will be re-batched. (I use 30 or 60 minute intervals).
  230.  
  231.   Don't redirect the output of uubatch to /dev/nul until you
  232.   have tested it for each node and seen it work. Do some loop mails
  233.   to make sure before running any crucial e-mail through it.
  234.  
  235.   
  236. Revision history :
  237.  
  238. 1.0.2 :        01-Aug-1991    First distributed version.
  239.  
  240. 1.0.3 :        13-Aug-1991    Fixed bugs :
  241.  
  242.         uubatch.c : batching process now correctly calculates
  243.         modifications time and size of job file. time and size
  244.         considerations now handled properly.
  245.  
  246.         uudebat.c : PMAX set to maximum path length on system
  247.         (instead of maximum filename length).
  248.  
  249. 1.0.4 :        uudebat.c : Fixed possible security hole, and added 
  250.         better error recovery and security warnings.
  251.  
  252.         uudebat.c : Added filtering of uubatch "escape" lines 
  253.         from X. files. This allows uubatch "protocol extensions"
  254.         in future versions, which may be needed to support
  255.         smarter stuff. Upward/Downward compatability will be
  256.         mantained through all future and past versions.
  257.  
  258.         uudebat.c : Removed line length limitation. Any length
  259.         line can now be passed through it.
  260.  
  261.         uubatch.c : Removed line length limitation. Any length
  262.         line can now be passed through it.
  263.  
  264.         uubatch.c : Several performance improvements including :
  265.         - moved directory searchs into uubatch.c
  266.         - allow batching for multiple uucp nodes in one run.
  267.         - removed unneeded 'cat' commands in some places.
  268.  
  269.         uubatch_run : removed this file. All batch execution 
  270.         is now performed entirely by uubatch.c, and uubatch.c
  271.         is the program to be called from cron from now on.
  272.  
  273.         uubatch.c and uudebat.c : some readability touch-ups.
  274.  
  275.         Makefile : Touched up a bit and added more tested 
  276.         machines.
  277.  
  278.  
  279. 1.0.5:    fix various uncontroled string copies.
  280.         Still in the works: mail bouncing, firewall.
  281.